/**
 * @file list.h
 * @author 
 * @brief list数据结构
 * @version 0.1
 * @date 2023-10-23
 * 
 * @copyright Copyright (c) 2023
 * 
 */

#ifndef LIST_H
#define LIST_H

#include <inttypes.h>

#define LIST_OK 0x0000

#define LIST_BAD_INPUT_DATA 0x0001
#define LIST_MALLOC_FAILED 0x0002
#define LIST_INDEX_BIGGER_THAN_MAX 0x0003
#define LIST_BUFFER_TOO_SMALL   0x0004

typedef struct list list;

/**
 * @brief list句柄初始化
 * 
 * @param handler 初始化句柄，需要传入二级指针，内部自动申请内存
 * @return int 返回操作状态
 */
int list_init(list **handler);

/**
 * @brief list添加一个元素，需要element需要外部malloc申请内存
 * 
 * @param handler list句柄
 * @param element 任意类型的指针，但是需要在接口外部malloc内存
 * @return int 返回操作状态
 */
int list_add(list *handler, void *element);

/**
 * @brief 添加到指定位置，index从1开始计数
 * 
 * @param handler list句柄
 * @param index 具体位置，从1开始
 * @param element 任意类型的指针，但是需要在接口外部malloc
 * @return int 返回操作状态
 */
int list_add_at(list *handler, int64_t index, void *element);

/**
 * @brief 替换element
 * 
 * @param handler list句柄
 * @param index 位置
 * @param element_in 替换进入的内容
 * @param element_out 替换输出的内容
 * @return int 返回操作状态
 */
int list_replace_at(list *handler, int64_t index, void *element_in, void **element_out);

/**
 * @brief 获得list的大小并存放到size中
 * 
 * @param handler list句柄
 * @param size 大小
 * @return int 返回操作状态
 */
int list_size(list *handler, int64_t *size);

/**
 * @brief 获得list中index处的一个元素，下标从1开始计算
 * 
 * @warning 获得的element是一个浅拷贝，仅仅只是把指针返回出来了，如果外部释放会导致程序崩溃；而且此处的element需要和add的时候是同样的类型
 * 
 * @param handler list句柄
 * @param index 位置
 * @param element 获得元素，返回的是指针，需要传入二级指针
 * @return int 返回操作状态
 */
int list_get_at(list *handler, int64_t index, void **element);

/**
 * @brief list导出，将handler中的所有内容导出到export_arr中，需要确保前后元素类型一致
 * 
 * @param handler list句柄
 * @param export_arr 导出的buffer
 * @param arr_size buffer大小
 * @param arr_length buffer输出长度
 * @return int 返回操作状态
 */
int list_export(list *handler, void *export_arr[], int64_t arr_size, int64_t *arr_length);

/**
 * @brief 释放list中所有的内存，并将handler指向NULL
 * 
 * @param handler list句柄
 * @return int 返回操作状态
 */
int list_free_all(list **handler);

/**
 * @brief 释放index处的内容
 * 
 * @param handler list句柄
 * @param index 位置
 * @return int 返回操作状态
 */
int list_free_at(list *handler, int index);

#endif /* LIST_H */
